Influencer Search API v1.0
The Social Animal Influencer Search API is a very powerful service deploying state-of-the-art algorithms to find you top influencers for pretty much any keyword. The simple-to-use API provides your systems high-quality influencer data leveraging which you can build very valuable products or services. We process and analyze close to a million top shared articles every day, finding you the influencers who really matter.
The Social Animal Influencer Search API is the only API on the market that can search for influencers based on keywords in the article URLs they share. This means you get real influencers based on what they really share on Twitter. This is important since most other APIs are based on content in the influencer's Twitter bio text or Tweets they share. Social Animal's powerful algorithms however look deep. They fetch articles shared by influencers and look for keywords in them. You can use the Social Animal Influencer Search API to search real influencers based on keywords in content they shared. This value passes directly on to your product or service you build on top of our APIs.
Things you need to know before you start
- The Social Animal Influencer Search API has two types of searches. One based on keywords in the content shared by influencers and the other, a search of their Twitter bio text. Both types of searches have their uses. The first type of search looks at keywords inside of article URLs shared by influencers. This makes it a very deep and powerful search and is very unique to Social Animal. The second type of search is a straigtforward search of the Twitter bio search. You can always sort the results by number of followers and get the most valuable influencers.
- Rate limit is 1 req/sec by default, but customizable according to the subscription plan upto 5 req/sec. See the support section in this document for more details.
Common Request Headers
X-User-Id
(String, required) -- Email ID used for the registered account.X-Auth-Key
(String, required) -- API key generated from the developer console.
Common Response Headers
X-Quota-Used
(Integer, required) -- Number of API calls made out of the available quota.X-Quota-Remaining
(Integer, required) -- Number of API calls remaining out of the available quota.
Influencer Search
The Social Animal's Influencer Search API is extremely simple. There is just one single RESTful API call, but you control what you get in the search results via different parameters you send it. In the following sections, we explain in detail the different filters and sorting options that will help you get the best out of the Social Animal Influencer API.
Influencer API
POST /api/v1/influencer/search
Request Object Parameters
Parameters control filtering and sorting. There is sufficient indication of whether parameters are mandatory, mutually exclusive, etc. Should you have any trouble using the Social Animal Content API, please see section below on support.
The Query
-
query
(Object, required) -- Query by the specified key. Possible key iskeyword
keyword
(String) –- Match one or more keywords in the articles or twitter profiles.
Simple Request Example
The following call fetches twitter profiles for "digital marketing". Twitter profile search is default search type.
POST /api/v1/influencer/search { "query": { "keyword": "digital marketing" } }
Types of Search
search_type
(String, Optional) -- Default search value istwitter_bios
. Other possible value isinfluencer
to search by keywords inside content of URLs shared by influencers.
Advanced Search Results Filtering
The Social Animal Influencer API allows you complete control of results through filters. You can specify multiple filters on influencers. If any filters are mutually exclusive, you’ll find it clearly indicated. there is no filters applicable for type
influencer.
filter
(Object, optional) -- Advanced filters to further refine the query. You can set multiple keys in the filter
object depending on what filters you want to apply. Please see below for the different filter keys you can use.
By Name
name
(String) - Match one or more twitter profile names. Results matching the name specified are returned.
By Location
location
(String) - Match one or more twitter profiles by specified location. Searches the location specified in the Twitter profile. Please be aware that this is a free text field and Twitter users are free to write whatever they want here and this might not be the name of a real place.
By Language
lang
(String) – Filter by the language in which the twitter user uses Twitter, e.g: en
, fr
, es
. Use two-letter language codes as specified in ISO-639-1.
By URL
url
(String) – Retrieve the twitter profiles that have specified this particular URL in their Twitter bio text.
By Minimum Followers
min_followers
(Integer) - Retrieve only those profiles having a minimum number of followers. By default, profiles irrespective of the number of followers are retrieved.
By Minimum Followings
min_followings
(Integer) - Retrieve only those profiles having a minimum number of followings. By default, profiles irrespective of the number of followings are retrieved. This is the count of Twitter profiles a particular Twitter users follows.
By Minimum Tweets
min_tweets
(Integer) - Retrieve only those profiles having a minimum number of tweets. By default, profiles irrespective of the number of tweets are retrieved.
By Maximum Followers
max_followers
(Integer) - Retrieve only those profiles having upto this number of followers. By default, profiles irrespective of the number followers are retrieved.
By Maximum Followings
max_followings
(Integer) - Retrieve only those profiles having upto this number of followings. By default, profiles irrespective of the number of followings are retrieved.
By Maximum Tweets
max_tweets
(Integer) - Retrieve only those profiles having upto this number of tweets. By default, profiles irrespective of the number tweets are retrieved.
Profile Search Vs. Bio Search.
is_profile_search
(Boolean) – This is set to True by default. If set to True, retrives profiles containing given keywords in the Twitter handle name or in the user’s Twitter bio text. Searches only Twitter handle name if this is set to False and ignores the text in the Twitter bio field.
Include Hash tag results.
is_hash_search
(Boolean) – This is set to True by default. Retrives profiles based on hashtags included in the Twitter bio text.
Sorting Content Results
You can control the sorting order of the results that are returned with sort related parameters.
Sorting Results
sort_by
(String, optional) -- Field by which to sort the results. Default value is followers_count
. Possible values are listed_count
, favourites_count
and statuses_count
.
Sort Order
sort_order
(String, optional) -- Order of sorting. Default value is DESC
. This sorts content in descending order by followers count on twitter. So, you’ll see the profiles that have the most followers on top. Possible values are ASC
and DESC
.
Paginating Results
Any call to the Social Animal Influencer API can return up to a maximum of 100 results. The folling parameters let you manage how the results are returned in a paginated fashion so that they are in manageable chunks for use in your own app or script.
results_per_page
(Integer, optional) -- The number of results that will be returned per page. Default value is100
. Possible values are10
,25
,50
and100
.offset
(Integer, optional) -– The offset from which the next page of results is retrieved. To get the next page of results, you can simply passnext_page_offset
which is sent as part of the response in your next call. Please see example below.max_results
(Integer, optional) –- The maximum number of results that should be returned. Default value is10000
. Acceptable values ranges from1
to10000
inclusively. Although not very useful, this is provided for the sake of completeness.
Request Example
{ "query": { "keyword": "iot" }, "filter": { "min_followers": 10000 }, "results_per_page": 2, "sort_by": "listed_count", "sort_order": "ASC" }
Response Success Parameters
status
(String, required) -- Will have valuesuccess
always.results_in_page
(Integer, required) -- The number of results included in the API response.next_page_offset
(Integer, required) -- The value to be passed foroffset
to retrieve the next page.total_results
(Integer, required) -- The total number of results in the result set.data
(Array, required) -- A list of influencer objects that match the request criteria.
Response Example
{ "status": "success", "total_results": 576, "data": [ { "utc_offset": -18000, "friends_count": 1, "profile_image_url_https": "https://pbs.twimg.com/profile_images/834139661014548480/ZiHs-2Z-_normal.jpg", "listed_count": 0, "default_profile_image": false, "favourites_count": 476, "verified": false, "description": "Eng., PhD, 6th Kyu #AI #DeepLearning #GenerativeArt #IoT #Wearables #Sensors #Biotech #SelfAwareness #EmotionalIntelligence #FutureOfWork", "created_at": "2017/02/24 05:48:57", "profile_image_url": "http://pbs.twimg.com/profile_images/834139661014548480/ZiHs-2Z-_normal.jpg", "time_zone": "Eastern Time (US & Canada)", "url": "http://alicia.heraz.free.fr", "account_created_at": "2017/02/21 08:32:16", "updated_at": "2017/02/24 05:48:57", "screen_name": "AliciaHeraz", "statuses_count": 9, "followers_count": 10565, "default_profile": false, "id_str": "834138693673898000", "name": "Alicia Heraz", "location": null, "id": 834138693673898000, "lang": "en", "category": "general" }, { "utc_offset": null, "friends_count": 84, "profile_image_url_https": "https://pbs.twimg.com/profile_images/976391378958733312/XyuLlCTf_normal.jpg", "listed_count": 0, "default_profile_image": false, "favourites_count": 35, "description": "Toschain official website:http://www.toschain.org\nTOS chain is a decentralization layered block network technology based on SDAG for the IOT.", "created_at": "2018/04/21 11:53:16", "account_created_at": "2018/03/21 09:28:44", "updated_at": "2018/04/21 11:53:16", "screen_name": "TOSCommuniy", "id_str": "976390138451304400", "id": 976390138451304400, "lang": "zh-CN", "verified": false, "profile_image_url": "http://pbs.twimg.com/profile_images/976391378958733312/XyuLlCTf_normal.jpg", "time_zone": null, "url": "http://www.toschain.org", "statuses_count": 25, "followers_count": 15788, "default_profile": false, "profile_use_background_image": false, "name": "Toschain", "location": null, "category": "general" } ], "results_in_page": 2, "next_page_offset": 2 }
Response Error Parameters
status
(String, required) -- Will have valueerror
always.message
(String, required) -- The response error message.
Response Error Codes
Code | Message |
---|---|
400 | Bad Request |
400 | Multiple Query Keys Specified |
400 | Invalid Parameter parameter_name |
401 | Unauthorized |
403 | Forbidden |
405 | Method Not Allowed |
429 | Rate Limit Exceeded |
429 | Quota Limit Exceeded |
500 | Internal Server Error |
Response Error Example
{ "status": "error", "message": "Bad Request" }
Support
Should you need any support regarding the Social Animal Content API subscription plans or developer support in general, please feel free to reach out to us at api@socialanimal.com.